<h1 id="introduction">Introduction</h1>

<p>Version: <span class="duktape-version">XX.XX.XX</span>
(<span class="current-date">XXXX-XX-XX</span>)</p>

<h2>Document scope</h2>

<p>This guide provides an introduction to using Duktape in your programs.
Once you're familiar with the basics, there is a concise
<a href="api.html">API reference</a> for looking up API details.  The
<a href="http://wiki.duktape.org">Duktape Wiki</a> provides more detailed
examples and best practices.</p>

<p>This document doesn't cover Duktape internals, see the
<a href="https://github.com/svaarala/duktape/tree/master/doc">Duktape repo</a>
if you wish to tinker with them.</p>

<h2>What is Duktape?</h2>

<p>Duktape is an embeddable ECMAScript&#174; engine with a focus on portability
and compact footprint.  By integrating Duktape into your C/C++ program you
can easily extend its functionality through scripting.  You can also build
the main control flow of your program in ECMAScript and use fast C code
functions to do heavy lifting.</p>

<p>Embeddability means that Duktape makes minimal assumptions about the
underlying platform and its capabilities; instead, the application which
embeds Duktape is in control of which native bindings are provided and
in what manner.  For example, there are no default bindings for printing
text to the console or to interact with the file system.  Duktape
distributable package includes example providers which you can easily
integrate if they suit your needs.</p>

<p>The terms ECMAScript and Javascript are often considered more or less
equivalent, although Javascript and its variants are technically just one
environment where the ECMAScript language is used.  The line between the
two is not very clear in practice: even non-browser ECMAScript environments
often provide some browser-specific built-ins.  Even so, we use the term
ECMAScript throughout to refer to the language implemented by Duktape.</p>

<h2>Conformance</h2>

<p>Duktape conforms to ES5.0/ES5.1 with semantics updated from ES2015 or
later where appropriate:</p>
<ul>
<li><a href="http://www.ecma-international.org/publications/files/ECMA-ST-ARCH/ECMA-262%205th%20edition%20December%202009.pdf">ECMAScript Language Specification 5th Edition</a></li>
<li><a href="http://www.ecma-international.org/ecma-262/5.1/">ECMAScript&#x00ae; Language Specification 5.1 Edition</a></li>
</ul>

<p>Duktape tracks the latest ECMAScript specification for semantics and
built-ins (however support for ES2015 and later is still incomplete), see:</p>
<ul>
<li><a href="http://www.ecma-international.org/ecma-262/6.0/">ECMAScript&#x00ae; 2015 Language Specification</a></li>
<li><a href="http://www.ecma-international.org/ecma-262/7.0/">ECMAScript&#x00ae; 2016 Language Specification</a></li>
</ul>

<p>In some specific cases Duktape may follow a specification draft,
see work in progress in <a href="https://github.com/tc39/ecma262">TC39/ecma262</a>.
This is done when a feature in the latest specifications conflicts
with real world code (see e.g. <a href="https://github.com/tc39/ecma262/pull/263">RegExp.prototype issues</a>).</p>

<p>TypedArray support is based on ES2016 TypedArray; initial implementation
was based on Khronos TypedArray specification:</p>
<ul>
<li><a href="https://www.khronos.org/registry/typedarray/specs/latest/">Typed Array Specification (Editor's Draft 18 July 2013)</a> (Note: link is to latest)</li>
<li><code>svn co -r 30720 https://cvs.khronos.org/svn/repos/registry/trunk/public/typedarray</code></li>
</ul>

<p>Node.js Buffer support is based on:</p>
<ul>
<li><a href="https://nodejs.org/docs/v6.9.1/api/buffer.html">Buffer Node.js v6.9.1</a></li>
</ul>

<p>TextEncoder() and TextDecoder() bindings are based on:</p>
<ul>
<li><a href="https://encoding.spec.whatwg.org/#api">Encoding API</a>, WHATWG Encoding Living Standard</li>
</ul>

<p>Performance.now() binding is based on:</p>
<ul>
<li><a href="https://www.w3.org/TR/hr-time/#dom-performance-now">High Resolution Time Level 2</a></li>
</ul>

<h2>Features</h2>

<p>Besides standard ECMAScript features, Duktape has the following additional
features (some are visible to applications, while others are internal):</p>
<ul>
<li>ES2015 <a href="https://www.khronos.org/registry/typedarray/specs/latest/">TypedArray</a>
    and <a href="https://nodejs.org/docs/v6.9.1/api/buffer.html">Node.js Buffer</a> bindings,
    plain buffer type (lightweight Uint8Array)</li>
<li>From ECMAScript 2015 (ES6): <code>setPrototypeOf</code>/<code>__proto__</code>,
    a subset of <code>Proxy</code> objects, <code>Reflect</code>, computed property names,
    and minimal <code>const</code> support</li>
<li>From ECMAScript 2016 (ES7): exponentiation operator (<code>**</code>, <code>**=</code>)</li>
<li><a href="https://encoding.spec.whatwg.org/#api">Encoding API</a> bindings based on the WHATWG Encoding Living Standard</li>
<li>Duktape specific built-ins: provided by the <code>Duktape</code> global object</li>
<li>Extended types: custom "buffer" and "pointer" types, extended string type
    which supports arbitary binary strings and
    non-<a href="http://en.wikipedia.org/wiki/Plane_(Unicode)#Basic_Multilingual_Plane">BMP</a>
    strings (standard ECMAScript only supports 16-bit codepoints)</li>
<li>Combined reference counting and mark-and-sweep garbage collection,
    with finalizers and emergency garbage collection (you can also build
    with just mark-and-sweep)</li>
<li>Coroutine support</li>
<li>Tail call support</li>
<li>Built-in debugger framework based on a debugger protocol</li>
<li>Built-in regular expression engine with no platform dependencies</li>
<li>Built-in Unicode support with no platform dependencies</li>
<li>Built-in number parsing and formatting with no platform dependencies</li>
<li>Built-in CBOR binding for binary serialization</li>
<li>Additional custom JSON formats (JX and JC)</li>
<li>Bytecode dump/load mechanism for caching compiled functions</li>
</ul>

<h2>Goals</h2>

<p><b>Compliance</b>.  ECMAScript E5/E5.1 and real world compliance.
ECMAScript compliance requires regular expression and Unicode support.
When possible, implement features from latest or draft ECMAScript
specifications to minimize Duktape custom features.</p>

<p><b>Portability</b>.  Minimal system dependencies are nice when porting,
so Duktape depends on very few system libraries.  For example, number
formatting and parsing, regular expressions, and Unicode are all implemented
internally by Duktape.  One of the few dependencies that cannot be fully
eliminated is system date/time integration in the <code>Date</code> built-in.
Duktape supports major platforms directly but you can also use an external
Date provider on exotic platforms.</p>

<p><b>Easy C interface</b>.  The interface between Duktape and C programs
should be natural and error-tolerant.  As a particular issue, string
representation should be UTF-8 with automatic NUL terminators to match
common C use.</p>

<p><b>Small footprint</b>.  Code and data footprint should be as small as
possible, even for small programs.  Duktape is portable even to "bare metal"
targets with no standard libraries.  This is more important than performance,
as there are already several very fast engines but fewer very compact,
portable engines.</p>

<p><b>Reasonable performance</b>.  Small footprint (and portability, to some
extent) probably eliminates the possibility of a competitive JIT-based engine,
so there is no practical way of competing with very advanced JIT-based engines
like SpiderMonkey (and its optimized variants) or Google V8.  Performance
should still be reasonable for typical embedded programs.
<a href="http://www.lua.org/">Lua</a> is a good benchmark in this respect.
(Adding optional, modular support for JITing or perhaps off-line compilation
would be nice.)</p>

<p><b>ASCII string performance</b>.  It's important that operations dealing
with plain ASCII strings be very fast: ASCII dominates most embedded use.
Operations dealing with non-ASCII strings need to perform reasonably but are
not critical.  This is a necessary trade-off: using C-compatible strings means
essentially using UTF-8 string representation which makes string indexing and
many other operations slower than with fixed size character representations.
It's still important to support common idioms like iterating strings sequentially
(in either direction) efficiently.</p>

<h2>Document organization</h2>

<p><a href="#gettingstarted">Getting started</a> guides you through downloading,
compiling, and integrating Duktape into your program.  It also provides concrete
examples of how you can integrate scripting capabilities into your program.</p>

<p><a href="#programming">Programming model</a>, <a href="#stacktypes">Stack types</a>,
and <a href="#ctypes">C types</a>
discuss core Duktape concepts such as <i>heap</i>, <i>context</i>, <i>value stacks</i>,
<i>Duktape API</i>, and <i>Duktape/C functions</i>.  Duktape stack types and C type
wrappers are discussed in detail.</p>

<p>Duktape specific ECMAScript features are discussed in multiple sections:
<a href="#typealgorithms">Type algorithms</a> (for custom types),
<a href="#duktapebuiltins">Duktape built-ins</a> (additional built-ins), 
<a href="#postes5features">Post-ES5 features</a> (features implemented from ES2016 and beyond),
<a href="#custombehavior">Custom behavior</a> (behavior differing from standard),
<a href="#customjson">Custom JSON formats</a>,
<a href="#customdirectives">Custom directives</a>,
<a href="#bufferobjects">Buffer objects</a>,
<a href="#errorobjects">Error objects</a> (properties and traceback support),
<a href="#functionobjects">Function objects</a> (properties),
<a href="#datetime">Date and time</a>,
<a href="#random">Random numbers</a>,
<a href="#debugger">Debugger</a>,
<a href="#modules">Modules</a>,
<a href="#finalization">Finalization</a>,
<a href="#coroutines">Coroutines</a>,
<a href="#virtualproperties">Virtual properties</a>,
<a href="#symbols">Symbols</a>,
<a href="#bytecodedumpload">Bytecode dump/load</a>,
<a href="#threading">Threading</a>,
<a href="#sandboxing">Sandboxing</a>.
</p>

<p><a href="#performance">Performance</a> provides a few Duktape-specific tips
for improving performance and avoiding performance pitfalls.
<a href="#memoryusage">Memory usage</a> summarizes Duktape memory usage and
gives pointers for minimizing it.
<a href="#compiling">Compiling</a> describes how to configure and compile Duktape
as part of your application.
<a href="#portability">Portability</a> covers platform and compiler specific
issues and other portability issues.
<a href="#compatibility">Compatibility</a> discusses Duktape's compatibility
with ECMAScript dialects, extensions, and frameworks.
<a href="#versioning">Versioning</a> describes Duktape versioning and what version
compatibility to expect.
<a href="#limitations">Limitations</a> summarizes currently known limitations
and provides possible workarounds.</p>

<p><a href="#comparisontolua">Comparison to Lua</a> discusses some differences
between Lua and Duktape; it may be useful reading if you're already familiar with Lua.</p>
